Libris Britannia 4/science library(b).zip/science library(b)/DJGPP/DJ111M2.ZIP/docs/djgpp/libc-t-z.tex

Text File | 1994-01-08 | 17KB | 820 lines

@c ----------------------------------------------------------------------
@node tell, telldir, system, Alphabetical List

@heading @code{tell}
@subheading Syntax

@example
long tell(int file);
@end example

@subheading Description

This function returns the location of the file pointer for @var{file}.

@subheading Return Value

The file pointer, or -1 on error.

@subheading Example

@example
long q = tell(fd);
@end example

@c ----------------------------------------------------------------------
@node telldir, tempnam, tell, Alphabetical List

@heading @code{telldir}
@subheading Syntax

@example
#include <dirent.h>

long telldir(DIR *dir);
@end example

@subheading Description

This function returns a value which indicates the position of the
pointer in the given directory.  This value is only useful as an
argument to @code{seekdir} (@xref{seekdir}).

@subheading Return Value

The directory pointer.

@subheading Example

@example
DIR *dir;
long q = telldir(dir);
do_something();
seekdir(dir, q);
@end example

@c ----------------------------------------------------------------------
@node tempnam, time, telldir, Alphabetical List

@heading @code{tempnam}
@subheading Syntax

@example
#include <stdio.h>

char *tempnam(const char *dir, const char *prefix);
@end example

@subheading Description

This function returns a temporary file name in a buffer allocated by
@code{malloc}.  The locations and filenames searched for temporary space
are as follows:

@example
getenv("TMPDIR")/@var{prefix}??????
@var{dir}/@var{prefix}??????
@code{P_tmpdir}/@var{prefix}??????
/tmp/@var{prefix}??????
@end example

@subheading Return Value

A pointer to the file name, or NULL if error.

@subheading Example

@example
char *fn = tempnam(".", "dj");
free(fn);
@end example

@c ----------------------------------------------------------------------
@node time, timezone, tempnam, Alphabetical List

@heading @code{time}
@subheading Syntax

@example
#include <time.h>

time_t time(time_t *t);
@end example

@subheading Description

If @var{t} is not @code{NULL}, the current time is stored in @code{*t}.

@subheading Return Value

The current time is returned.

@subheading Example

@example
printf("Time is %d\n", time(0));
@end example

@c ----------------------------------------------------------------------
@node timezone, tmpfile, time, Alphabetical List

@heading @code{timezone}
@subheading Syntax

@example
#include <time.h>

char *timezone(int minutes, int daylight);
@end example

@subheading Description

Given the number of minutes west of GMT and whether or not daylight
savings time is in affect, returns the name of the timezone.

If the environment variable TZNAME is set, it should be like
@code{EST,EDT}, and the name of the timezone will come from that.

@subheading Return Value

A pointer to the timezone or @code{NULL} if invalid.

@subheading Example

@example
printf("EST ? %s\n", timezone(5*60, 0));
@end example

@c ----------------------------------------------------------------------
@node tmpfile, tmpnam, timezone, Alphabetical List

@heading @code{tmpfile}
@subheading Syntax

@example
#include <stdio.h>

FILE *tmpfile(void);
@end example

@subheading Description

This function opens a temporary file.  It will automatically be removed
when the program exits.

@subheading Return Value

A newly opened file.

@subheading Example

@example
FILE *tmp = tmpfile();
@end example

@c ----------------------------------------------------------------------
@node tmpnam, tolower, tmpfile, Alphabetical List

@heading @code{tmpnam}
@subheading Syntax

@example
#include <stdio.h>

char *tmpnam(char *s);
@end example

@subheading Description

If @var{s} is NULL, a buffer is allocated, else @var{s} is used to hold
the name of a unique file.

@subheading Return Value

A pointer to the new file name.

@subheading Example

@example
char buf[PATH_MAX];
char *s = tmpname(buf);
@end example

@c ----------------------------------------------------------------------
@node tolower, toupper, tmpnam, Alphabetical List

@heading @code{tolower}
@subheading Syntax

@example
#include <ctype.h>

int tolower(int c);
@end example

@subheading Description

This function returns @var{c}, converting it to lower case if it is
upper case.  @xref{toupper}

@subheading Return Value

The upper case letter.

@subheading Example

@example
for (i=0; buf[i]; i++)
  buf[i] = tolower(buf[i]);
@end example

@c ----------------------------------------------------------------------
@node toupper, truncate, tolower, Alphabetical List

@heading @code{toupper}
@subheading Syntax

@example
#include <ctype.h>

int toupper(int c);
@end example

@subheading Description

This function returns @var{c}, converting it to upper case if it is
lower case. @xref{tolower}

@subheading Return Value

The upper case letter.

@subheading Example

@example
for (i=0; buf[i]; i++)
  buf[i] = toupper(buf[i]);
@end example

@c ----------------------------------------------------------------------
@node truncate, ttyname, toupper, Alphabetical List

@heading @code{truncate}
@subheading Syntax

@example
#include <osfcn.h>

int truncate(const char *file, unsigned long size);
@end example

@subheading Description

This function truncates @var{file} to @var{size} bytes.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Example

@example
ftruncate("/tmp/data.txt", 400);
@end example

@c ----------------------------------------------------------------------
@node ttyname, tzname, truncate, Alphabetical List

@heading @code{ttyname}
@subheading Syntax

@example
#include <osfcn.h>

char *ttyname(int file);
@end example

@subheading Description

Gives the name of the terminal associated with @var{file}.

@subheading Return Value

Returns "/dev/con" if @var{file} is a device, else @code{NULL}.

@subheading Example

@example
char *tty = ttyname(0);
@end example

@c ----------------------------------------------------------------------
@node tzname, tzset, ttyname, Alphabetical List

@heading @code{tzname}
@subheading Syntax

@example
extern char *tzname[2]
@end example

@subheading Description

This array holds the names of standard and daylight savings timezones
for the local area.  You must call @code{tzset} to initialize these.

@c ----------------------------------------------------------------------
@node tzset, tzsetwall, tzname, Alphabetical List

@heading @code{tzset}
@subheading Syntax

@example
#include <time.h>

void tzset(void);
@end example

@subheading Description

This function initializes the timezone information.

@subheading Return Value

None.

@c ----------------------------------------------------------------------
@node tzsetwall, _tztab, tzset, Alphabetical List

@heading @code{tzsetwall}
@subheading Syntax

@example
#include <time.h>

void tzsetwall(void)
@end example

@subheading Description

This function initializes the system to "wall clock" time.

@subheading Return Value

None.

@c ----------------------------------------------------------------------
@node _tztab, umask, tzsetwall, Alphabetical List

@heading @code{_tztab}

@subheading Description

This is an internal variable used by the @code{tz} functions.

@c ----------------------------------------------------------------------
@node umask, ungetc, _tztab, Alphabetical List

@heading @code{umask}

@subheading Description

This is an internal function used by gcc to help perform certain
operations.

@c ----------------------------------------------------------------------
@node ungetc, unlink, umask, Alphabetical List

@heading @code{ungetc}
@subheading Syntax

@example
#include <stdio.h>

int ungetc(int c, FILE *file);
@end example

@subheading Description

This function pushes @var{c} back into the @var{file}.  You can only
push back one character at a time.

@subheading Return Value

The pushed-back character, or @code{EOF} on error.

@subheading Example

@example
int q;
while (q = getc(stdin) != 'q');
ungetc(q);
@end example

@c ----------------------------------------------------------------------
@node unlink, unlock, ungetc, Alphabetical List

@heading @code{unlink}
@subheading Syntax

@example
#include <osfcn.h>

int unlink(const char *file);
@end example

@subheading Description

This function removes a file from the file system.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Example

@example
unlink("data.txt");
@end example

@c ----------------------------------------------------------------------
@node unlock, unsetenv, unlink, Alphabetical List

@heading @code{unlock}
@subheading Syntax

@example
#include <io.h>

int unlock(int fd, long offset, long length);
@end example

@subheading Description
Unlocks a region previously locked by @code{lock}.

@xref{lock}.

@subheading Return Value
Zero if successful, nonzero if not.

@c ----------------------------------------------------------------------
@node unsetenv, usleep, unlock, Alphabetical List

@heading @code{unsetenv}
@subheading Syntax

@example
#include <stdlib.h>

void unsetenv(const char *name);
@end example

@subheading Description

This function removes the given environment variable from the
environment.

@subheading Return Value

None.

@subheading Example

@example
unsetenv("TERM");
@end example

@c ----------------------------------------------------------------------
@node usleep, utime, unsetenv, Alphabetical List

@heading @code{usleep}
@subheading Syntax

@example
#include <osfcn.h>

unsigned usleep(unsigned usec);
@end example

@subheading Description

This function pauses the program for @var{usec} microseconds.

@subheading Return Value

The number of unsleept microseconds (i.e. zero).

@subheading Example

@example
usleep(500000);
@end example

@c ----------------------------------------------------------------------
@node utime, utimes, usleep, Alphabetical List

@heading @code{utime}
@subheading Syntax

@example
#include <utime.h>

itn utime(const char *file, const struct utimbuf *time);
@end example

@subheading Description

This function sets the modification timestamp on the @var{file}.  The
new time is stored in this structure:

@example
struct utimbuf
@{
    time_t  actime;  /* access time (unused) */
    time_t  modtime; /* modification time */
@};
@end example

@subheading Return Value

Zero for success, nonzero for failure.

@subheading Example

@example
struct utimbuf t;
t.modtime = time(0);
utime("data.txt", &t);
@end example

@c ----------------------------------------------------------------------
@node utimes, valloc, utime, Alphabetical List

@heading @code{utimes}
@subheading Syntax

@example
int utimes(const char *file, struct timevar tvp[2]);
@end example

@subheading Description

This function does nothing.  It is provided to assist in
porting Unix programs.

@subheading Return Value

Zero for success, nonzero for failure.

@c ----------------------------------------------------------------------
@node valloc, vfork, utimes, Alphabetical List

@heading @code{valloc}
@subheading Syntax

@example
#include <stdlib.h>

void *valloc(unsigned size);
@end example

@subheading Description

This function is just like @code{malloc} (@xref{malloc}) except that the
returned pointer is always aligned to a CPU page boundary.  This
alignment is rarely useful in djgpp.

@subheading Return Value

A pointer to a newly allocated block of memory.

@subheading Example

@example
char *page = valloc(getpagesize());
@end example

@c ----------------------------------------------------------------------
@node vfork, vfprintf, valloc, Alphabetical List

@heading @code{vfork}

@subheading Description

This function is provided to assist in porting Unix programs only.  It
always fails.

@subheading Return Value

-1

@c ----------------------------------------------------------------------
@node vfprintf, vprintf, vfork, Alphabetical List

@heading @code{vfprintf}
@subheading Syntax

@example
#include <stdio.h>
#include <stdarg.h>

int vfprintf(FILE *file, const char *format, va_list arguments);
@end example

@subheading Description

Sends formatted output from the @var{arguments} to the @var{file}.
@xref{printf}

@subheading Return Value

The number of characters written.

@c ----------------------------------------------------------------------
@node vprintf, vsprintf, vfprintf, Alphabetical List

@heading @code{vprintf}
@subheading Syntax

@example
#include <stdio.h>
#include <stdarg.h>

int vprintf(const char *format, va_list arguments);
@end example

@subheading Description

Sends formatted output from the @var{arguments} to @code{stdout}.
@xref{printf}

@subheading Return Value

The number of characters written.

@c ----------------------------------------------------------------------
@node vsprintf, wait, vprintf, Alphabetical List

@heading @code{vsprintf}
@subheading Syntax

@example
#include <stdio.h>
#include <stdarg.h>

int vsprintf(char *buffer, const char *format, va_list arguments);
@end example

@subheading Description

Sends formatted output from the @var{arguments} to the @var{buffer}.
@xref{printf}

@subheading Return Value

The number of characters written.

@c ----------------------------------------------------------------------
@node wait, write, vsprintf, Alphabetical List

@heading @code{wait}

@subheading Description

This function is provided only to assist in porting from Unix.  It
always returns an error condition.

@c ----------------------------------------------------------------------
@node write, writecr, wait, Alphabetical List

@heading @code{write}
@subheading Syntax

@example
#include <osfcn.h>

int write(int file, const void *buffer, unsigned count);
@end example

@subheading Description

This function writes @var{count} bytes from @var{buffer} to @var{file}.
It returns the number of bytes actually written.  It will return zero at
end-of-file, and may return less than @var{count} even under valid
conditions.

Note that if @var{file} is a text file, @code{write} may write more
bytes than it reports.

@subheading Return Value

The number of bytes written, zero at EOF, or -1 on error.

@subheading Example

@example
write(fd, "hello", 5);
@end example

@c ----------------------------------------------------------------------
@node writecr, writev, write, Alphabetical List

@heading @code{writecr}
@subheading Syntax

@example
int write(int file, const void *buffer, unsigned count);
@end example

@subheading Description

This is just like @code{write} (@xref{write}) except that the Ctrl-M
characters are inserted before each Ctrl-J character to convert from
Unix-style text lines to DOS-style text lines when writing to a binary
file.

@subheading Return Value

The number of bytes written, zero at EOF, or -1 on error.

@subheading Example

@example
writecr(fd, "hello\n", 6);
@end example

@c ----------------------------------------------------------------------
@node writev, xmalloc, writecr, Alphabetical List

@heading @code{writev}
@subheading Syntax

@example
#include <sys/uio.h>

int writev(int handle, struct iovec *iov, int count);
@end example

@subheading Description

This is just like @code{readv} (@xref{readv}), except that it writes
instead of reading.

@subheading Return Value

The number of bytes written.

@c ----------------------------------------------------------------------
@node xmalloc, xrealloc, writev, Alphabetical List

@heading @code{xmalloc}
@subheading Syntax

@example
void *xmalloc(size_t size);
@end example

@subheading Description

This function is just like @code{malloc} (@xref{malloc}), except that if
there is no more memory, it prints an error message and exits.

@subheading Return Value

A pointer to the newly allocated memory.

@subheading Example

@example
char *f = xmalloc(100);
@end example

@c ----------------------------------------------------------------------
@node xrealloc, , xmalloc, Alphabetical List

@heading @code{xrealloc}
@subheading Syntax

@example
void *xrealloc(void *ptr, size_t size);
@end example

@subheading Description

This function is just like @code{realloc} (@xref{realloc}), except that
if there is no more memory, it prints an error message and exits.  It
can also properly handle @var{ptr} being @code{NULL}.

@subheading Return Value

A pointer to a possibly new block.

@subheading Example

@example
char *buf;
buf = (char *)xrealloc(buf, new_size);
@end example